<!DOCTYPE html>

<html>

<head>

<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />

<meta name="viewport" content="width=device-width, initial-scale=1" />



<title>Introduction to renv</title>

<script>// Pandoc 2.9 adds attributes on both header and div. We remove the former (to
// be compatible with the behavior of Pandoc < 2.8).
document.addEventListener('DOMContentLoaded', function(e) {
  var hs = document.querySelectorAll("div.section[class*='level'] > :first-child");
  var i, h, a;
  for (i = 0; i < hs.length; i++) {
    h = hs[i];
    if (!/^h[1-6]$/i.test(h.tagName)) continue;  // it should be a header h1-h6
    a = h.attributes;
    while (a.length > 0) h.removeAttribute(a[0].name);
  }
});
</script>

<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>



<style type="text/css">
code {
white-space: pre;
}
.sourceCode {
overflow: visible;
}
</style>
<style type="text/css" data-origin="pandoc">
html { -webkit-text-size-adjust: 100%; }
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code
{ counter-reset: source-line 0; }
pre.numberSource code > span
{ position: relative; left: -4em; counter-increment: source-line; }
pre.numberSource code > span > a:first-child::before
{ content: counter(source-line);
position: relative; left: -1em; text-align: right; vertical-align: baseline;
border: none; display: inline-block;
-webkit-touch-callout: none; -webkit-user-select: none;
-khtml-user-select: none; -moz-user-select: none;
-ms-user-select: none; user-select: none;
padding: 0 4px; width: 4em;
color: #aaaaaa;
}
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
div.sourceCode
{ }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
}
code span.al { color: #ff0000; font-weight: bold; } 
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.at { color: #7d9029; } 
code span.bn { color: #40a070; } 
code span.bu { color: #008000; } 
code span.cf { color: #007020; font-weight: bold; } 
code span.ch { color: #4070a0; } 
code span.cn { color: #880000; } 
code span.co { color: #60a0b0; font-style: italic; } 
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.do { color: #ba2121; font-style: italic; } 
code span.dt { color: #902000; } 
code span.dv { color: #40a070; } 
code span.er { color: #ff0000; font-weight: bold; } 
code span.ex { } 
code span.fl { color: #40a070; } 
code span.fu { color: #06287e; } 
code span.im { color: #008000; font-weight: bold; } 
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } 
code span.kw { color: #007020; font-weight: bold; } 
code span.op { color: #666666; } 
code span.ot { color: #007020; } 
code span.pp { color: #bc7a00; } 
code span.sc { color: #4070a0; } 
code span.ss { color: #bb6688; } 
code span.st { color: #4070a0; } 
code span.va { color: #19177c; } 
code span.vs { color: #4070a0; } 
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } 
</style>
<script>
// apply pandoc div.sourceCode style to pre.sourceCode instead
(function() {
  var sheets = document.styleSheets;
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue;
    try { var rules = sheets[i].cssRules; } catch (e) { continue; }
    var j = 0;
    while (j < rules.length) {
      var rule = rules[j];
      // check if there is a div.sourceCode rule
      if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") {
        j++;
        continue;
      }
      var style = rule.style.cssText;
      // check if color or background-color is set
      if (rule.style.color === '' && rule.style.backgroundColor === '') {
        j++;
        continue;
      }
      // replace div.sourceCode by a pre.sourceCode rule
      sheets[i].deleteRule(j);
      sheets[i].insertRule('pre.sourceCode{' + style + '}', j);
    }
  }
})();
</script>




<style type="text/css">body {
background-color: #fff;
margin: 1em auto;
max-width: 700px;
overflow: visible;
padding-left: 2em;
padding-right: 2em;
font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
font-size: 14px;
line-height: 1.35;
}
#TOC {
clear: both;
margin: 0 0 10px 10px;
padding: 4px;
width: 400px;
border: 1px solid #CCCCCC;
border-radius: 5px;
background-color: #f6f6f6;
font-size: 13px;
line-height: 1.3;
}
#TOC .toctitle {
font-weight: bold;
font-size: 15px;
margin-left: 5px;
}
#TOC ul {
padding-left: 40px;
margin-left: -1.5em;
margin-top: 5px;
margin-bottom: 5px;
}
#TOC ul ul {
margin-left: -2em;
}
#TOC li {
line-height: 16px;
}
table {
margin: 1em auto;
border-width: 1px;
border-color: #DDDDDD;
border-style: outset;
border-collapse: collapse;
}
table th {
border-width: 2px;
padding: 5px;
border-style: inset;
}
table td {
border-width: 1px;
border-style: inset;
line-height: 18px;
padding: 5px 5px;
}
table, table th, table td {
border-left-style: none;
border-right-style: none;
}
table thead, table tr.even {
background-color: #f7f7f7;
}
p {
margin: 0.5em 0;
}
blockquote {
background-color: #f6f6f6;
padding: 0.25em 0.75em;
}
hr {
border-style: solid;
border: none;
border-top: 1px solid #777;
margin: 28px 0;
}
dl {
margin-left: 0;
}
dl dd {
margin-bottom: 13px;
margin-left: 13px;
}
dl dt {
font-weight: bold;
}
ul {
margin-top: 0;
}
ul li {
list-style: circle outside;
}
ul ul {
margin-bottom: 0;
}
pre, code {
background-color: #f7f7f7;
border-radius: 3px;
color: #333;
white-space: pre-wrap; 
}
pre {
border-radius: 3px;
margin: 5px 0px 10px 0px;
padding: 10px;
}
pre:not([class]) {
background-color: #f7f7f7;
}
code {
font-family: Consolas, Monaco, 'Courier New', monospace;
font-size: 85%;
}
p > code, li > code {
padding: 2px 0px;
}
div.figure {
text-align: center;
}
img {
background-color: #FFFFFF;
padding: 2px;
border: 1px solid #DDDDDD;
border-radius: 3px;
border: 1px solid #CCCCCC;
margin: 0 5px;
}
h1 {
margin-top: 0;
font-size: 35px;
line-height: 40px;
}
h2 {
border-bottom: 4px solid #f7f7f7;
padding-top: 10px;
padding-bottom: 2px;
font-size: 145%;
}
h3 {
border-bottom: 2px solid #f7f7f7;
padding-top: 10px;
font-size: 120%;
}
h4 {
border-bottom: 1px solid #f7f7f7;
margin-left: 8px;
font-size: 105%;
}
h5, h6 {
border-bottom: 1px solid #ccc;
font-size: 105%;
}
a {
color: #0033dd;
text-decoration: none;
}
a:hover {
color: #6666ff; }
a:visited {
color: #800080; }
a:visited:hover {
color: #BB00BB; }
a[href^="http:"] {
text-decoration: underline; }
a[href^="https:"] {
text-decoration: underline; }

code > span.kw { color: #555; font-weight: bold; } 
code > span.dt { color: #902000; } 
code > span.dv { color: #40a070; } 
code > span.bn { color: #d14; } 
code > span.fl { color: #d14; } 
code > span.ch { color: #d14; } 
code > span.st { color: #d14; } 
code > span.co { color: #888888; font-style: italic; } 
code > span.ot { color: #007020; } 
code > span.al { color: #ff0000; font-weight: bold; } 
code > span.fu { color: #900; font-weight: bold; } 
code > span.er { color: #a61717; background-color: #e3d2d2; } 
</style>




</head>

<body>




<h1 class="title toc-ignore">Introduction to renv</h1>



<p>The renv package helps you create reproducible environments for your
R projects. This vignette introduces you to the basic nouns and verbs of
renv, like the user and project libraries, and key functions like
<code>renv::init()</code>, <code>renv::snapshot()</code> and
<code>renv::restore()</code>. You’ll also learn about some of the
infrastructure that makes renv tick, some problems that renv doesn’t
help with, and how to uninstall it if you no longer want to use it.</p>
<p>We assume you’re already living a project-centric lifestyle and are
familiar with a version control system, like Git and GitHub: we believe
these are table stakes for reproducible data science. If you’re not
already using projects, we recommend <a href="https://r4ds.had.co.nz/workflow-projects.html">Workflow:
Projects</a> from <em>R for Data Science</em>; if you’re unfamiliar with
<a href="https://git-scm.com/">Git</a> and <a href="https://github.com/">GitHub</a>, we recommend <a href="https://happygitwithr.com">Happy Git and GitHub for the
useR</a>.</p>
<div id="libraries-and-repositories" class="section level2">
<h2>Libraries and repositories</h2>
<p>Before we get into how renv works, you’ll learn to fully understand
two important pieces of R jargon: libraries and repositories.</p>
<p>A <strong>library</strong> is a directory containing installed
packages. This term is confusing because you write (e.g.)
<code>library(dplyr)</code>, making it easy to think that you’re loading
the dplyr library, not the dplyr package. That confusion doesn’t usually
matter because you don’t have to think about libraries, simply
installing all packages into a <strong>system library</strong><a href="#fn1" class="footnote-ref" id="fnref1"><sup>1</sup></a> that’s
shared across all projects. With renv, you’ll start using
<strong>project libraries,</strong> giving each project its own
independent collection of packages.</p>
<p>You can see your current libraries with <code>.libPaths()</code> and
see which packages are available in each library with
<code>lapply(.libPaths(), list.files)</code>.</p>
<p>A <strong>repository</strong> is a source of packages;
<code>install.packages()</code> gets a package from a repository
(usually somewhere on the Internet) and puts it in a library (a
directory on your computer). The most important repository is CRAN; you
can install packages from CRAN in just about every R session. Other
freely available repositories include <a href="https://bioconductor.org">Bioconductor</a>, the <a href="https://packagemanager.posit.co">Posit Public Package Manager</a>,
and <a href="https://r-universe.dev/">R Universe</a> (which turns GitHub
organisations into repositories).</p>
<p>You can see which repositories are currently set up in your session
with <code>getOption(&quot;repos&quot;)</code>; when you call
<code>install.packages(&quot;{pkgname}&quot;)</code>, R will look for
<code>pkgname</code> in each repository in turn.</p>
</div>
<div id="getting-started" class="section level2">
<h2>Getting started</h2>
<p>To convert a project to use renv, call <code>renv::init()</code>. It
adds three new files and directories to your project:</p>
<ul>
<li>The project library, <code>renv/library</code>, is a library that
contains all packages currently used by your project<a href="#fn2" class="footnote-ref" id="fnref2"><sup>2</sup></a>. This is the key magic
that makes renv work: instead of having one library containing the
packages used in every project, renv gives you a separate library for
each project. This gives you the benefits of <strong>isolation</strong>:
different projects can use different versions of packages, and
installing, updating, or removing packages in one project doesn’t affect
any other project.</li>
<li>The <strong>lockfile</strong>, <code>renv.lock</code>, records
enough metadata about every package that it can be re-installed on a new
machine. We’ll come back to the lockfile shortly when we talk about
<code>renv::snapshot()</code> and <code>renv::restore()</code>.</li>
<li>A project R profile, <code>.Rprofile</code>. This file is run
automatically every time you start R (in that project), and renv uses it
to configure your R session to use the project library. This ensures
that once you turn on renv for a project, it stays on, until you
deliberately turn it off.</li>
</ul>
<p>The next important pair of tools is <code>renv::snapshot()</code> and
<code>renv::restore()</code>. <code>snapshot()</code> updates the
lockfile with metadata about the currently-used packages in the project
library. This is useful because you can then share the lockfile and
other people or other computers can easily reproduce your current
environment by running <code>restore()</code>, which uses the metadata
from the lockfile to install exactly the same version of every package.
This pair of functions gives you the benefits of
<strong>reproducibility</strong> and <strong>portability</strong>: you
are now tracking exactly which package versions you have installed so
you can recreate them on other machines.</p>
<p>Now that you’ve got the high-level lay of the land, we’ll show a
couple of specific workflows before discussing some of the
reproducibility challenges that renv doesn’t currently help with.</p>
<div id="collaboration" class="section level3">
<h3>Collaboration</h3>
<p>One of the reasons to use renv is to make it easier to share your
code in such a way that everyone gets exactly the same package versions
as you. As above, you’ll start by calling <code>renv::init()</code>.
You’ll then need to commit <code>renv.lock</code>,
<code>.Rprofile</code>, <code>renv/settings.json</code> and
<code>renv/activate.R</code> to version control, ensuring that others
can recreate your project environment. If you’re using git, this is
particularly simple because renv will create a <code>.gitignore</code>
for you, and you can just commit all suggested files<a href="#fn3" class="footnote-ref" id="fnref3"><sup>3</sup></a>.</p>
<p>Now when one of your collaborators opens this project, renv will
automatically bootstrap itself, downloading and installing the
appropriate version of renv. It will also ask them if they want to
download and install all the packages it needs by running
<code>renv::restore()</code>.</p>
</div>
<div id="installing-packages" class="section level3">
<h3>Installing packages</h3>
<p>Over time, your project will need more packages. One of the
philosophies of renv is that your existing package management workflows
should continue to work, so you can continue to use familiar tools like
<code>install.packages()</code><a href="#fn4" class="footnote-ref" id="fnref4"><sup>4</sup></a>. But you can also use
<code>renv::install()</code>: it’s a little less typing and can install
packages from GitHub, Bioconductor, and more, not just CRAN.</p>
<p>If you use renv for multiple projects, you’ll have multiple
libraries, meaning that you’ll often need to install the same package in
multiple places. It would be annoying if you had to download (or worse,
compile) the package repeatedly, so renv uses a package cache. That
means you only ever have to download and install a package once, and for
each subsequent install, renv will just add a link from the project
library to the global cache. You can learn more about the cache in
<code>vignette(&quot;package-install&quot;)</code>.</p>
<p>After installing the package and checking that your code works, you
should call <code>renv::snapshot()</code> to record the latest package
versions in your lockfile. If you’re collaborating with others, you’ll
need to commit those changes to git, and let them know that you’ve
updated the lockfile and they should call <code>renv::restore()</code>
when they’re next working on a project.</p>
</div>
<div id="updating-packages" class="section level3">
<h3>Updating packages</h3>
<p>It’s worth noting that there’s a small risk associated with
isolation: while your code will never break due to a change in another
package, it will also never benefit from bug fixes. So for packages
under active development, we recommend that you regularly (at least once
a year) use <code>renv::update()</code><a href="#fn5" class="footnote-ref" id="fnref5"><sup>5</sup></a> to get the latest
versions of all dependencies. Similarly, if you’re making major changes
to a project that you haven’t worked on for a while, it’s often a good
idea to start with an <code>renv::update()</code> before making any
changes to the code.</p>
<p>After calling <code>renv::update()</code>, you should run the code in
your project and verify that it still works (or make any changes needed
to get it working). Then call <code>renv::snapshot()</code> to record
the new versions in the lockfile. If you get stuck, and can’t get the
project to work with the new versions, you can call
<code>renv::restore()</code> to roll back changes to the project library
and revert to the known good state recorded in your lockfile. If you
need to roll back to an even older version, take a look at
<code>renv::history()</code> and <code>renv::revert()</code>.</p>
<p><code>renv::update()</code> will also update renv itself, ensuring
that you get all the latest features. See <code>renv::upgrade()</code>
if you ever want to upgrade just renv, or you need to install a
development version from GitHub.</p>
</div>
</div>
<div id="infrastructure" class="section level2">
<h2>Infrastructure</h2>
<p>Now that you’ve got the basic usage of renv under your belt, it’s
time to learn a bit more about how the lockfile works. You won’t
typically edit this file directly, but you’ll see it changing in your
git commits, so it’s good to have a sense for what it looks like.</p>
<p>The lockfile is always called <code>renv.lock</code> and is a json
file that records all the information needed to recreate your project in
the future. Here’s an example lockfile, with the markdown package
installed from CRAN and the mime package installed from GitHub:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode json"><code class="sourceCode json"><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a><span class="fu">{</span></span>
<span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a>  <span class="dt">&quot;R&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb1-3"><a href="#cb1-3" tabindex="-1"></a>    <span class="dt">&quot;Version&quot;</span><span class="fu">:</span> <span class="st">&quot;4.5.1&quot;</span><span class="fu">,</span></span>
<span id="cb1-4"><a href="#cb1-4" tabindex="-1"></a>    <span class="dt">&quot;Repositories&quot;</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb1-5"><a href="#cb1-5" tabindex="-1"></a>      <span class="fu">{</span></span>
<span id="cb1-6"><a href="#cb1-6" tabindex="-1"></a>        <span class="dt">&quot;Name&quot;</span><span class="fu">:</span> <span class="st">&quot;CRAN&quot;</span><span class="fu">,</span></span>
<span id="cb1-7"><a href="#cb1-7" tabindex="-1"></a>        <span class="dt">&quot;URL&quot;</span><span class="fu">:</span> <span class="st">&quot;https://cloud.r-project.org&quot;</span></span>
<span id="cb1-8"><a href="#cb1-8" tabindex="-1"></a>      <span class="fu">}</span></span>
<span id="cb1-9"><a href="#cb1-9" tabindex="-1"></a>    <span class="ot">]</span></span>
<span id="cb1-10"><a href="#cb1-10" tabindex="-1"></a>  <span class="fu">},</span></span>
<span id="cb1-11"><a href="#cb1-11" tabindex="-1"></a>  <span class="dt">&quot;Packages&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb1-12"><a href="#cb1-12" tabindex="-1"></a>    <span class="dt">&quot;markdown&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb1-13"><a href="#cb1-13" tabindex="-1"></a>      <span class="dt">&quot;Package&quot;</span><span class="fu">:</span> <span class="st">&quot;markdown&quot;</span><span class="fu">,</span></span>
<span id="cb1-14"><a href="#cb1-14" tabindex="-1"></a>      <span class="dt">&quot;Version&quot;</span><span class="fu">:</span> <span class="st">&quot;1.0&quot;</span><span class="fu">,</span></span>
<span id="cb1-15"><a href="#cb1-15" tabindex="-1"></a>      <span class="dt">&quot;Source&quot;</span><span class="fu">:</span> <span class="st">&quot;Repository&quot;</span><span class="fu">,</span></span>
<span id="cb1-16"><a href="#cb1-16" tabindex="-1"></a>      <span class="dt">&quot;Repository&quot;</span><span class="fu">:</span> <span class="st">&quot;CRAN&quot;</span><span class="fu">,</span></span>
<span id="cb1-17"><a href="#cb1-17" tabindex="-1"></a>      <span class="dt">&quot;Hash&quot;</span><span class="fu">:</span> <span class="st">&quot;4584a57f565dd7987d59dda3a02cfb41&quot;</span></span>
<span id="cb1-18"><a href="#cb1-18" tabindex="-1"></a>    <span class="fu">},</span></span>
<span id="cb1-19"><a href="#cb1-19" tabindex="-1"></a>    <span class="dt">&quot;mime&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
<span id="cb1-20"><a href="#cb1-20" tabindex="-1"></a>      <span class="dt">&quot;Package&quot;</span><span class="fu">:</span> <span class="st">&quot;mime&quot;</span><span class="fu">,</span></span>
<span id="cb1-21"><a href="#cb1-21" tabindex="-1"></a>      <span class="dt">&quot;Version&quot;</span><span class="fu">:</span> <span class="st">&quot;0.12.1&quot;</span><span class="fu">,</span></span>
<span id="cb1-22"><a href="#cb1-22" tabindex="-1"></a>      <span class="dt">&quot;Source&quot;</span><span class="fu">:</span> <span class="st">&quot;GitHub&quot;</span><span class="fu">,</span></span>
<span id="cb1-23"><a href="#cb1-23" tabindex="-1"></a>      <span class="dt">&quot;RemoteType&quot;</span><span class="fu">:</span> <span class="st">&quot;github&quot;</span><span class="fu">,</span></span>
<span id="cb1-24"><a href="#cb1-24" tabindex="-1"></a>      <span class="dt">&quot;RemoteHost&quot;</span><span class="fu">:</span> <span class="st">&quot;api.github.com&quot;</span><span class="fu">,</span></span>
<span id="cb1-25"><a href="#cb1-25" tabindex="-1"></a>      <span class="dt">&quot;RemoteUsername&quot;</span><span class="fu">:</span> <span class="st">&quot;yihui&quot;</span><span class="fu">,</span></span>
<span id="cb1-26"><a href="#cb1-26" tabindex="-1"></a>      <span class="dt">&quot;RemoteRepo&quot;</span><span class="fu">:</span> <span class="st">&quot;mime&quot;</span><span class="fu">,</span></span>
<span id="cb1-27"><a href="#cb1-27" tabindex="-1"></a>      <span class="dt">&quot;RemoteRef&quot;</span><span class="fu">:</span> <span class="st">&quot;main&quot;</span><span class="fu">,</span></span>
<span id="cb1-28"><a href="#cb1-28" tabindex="-1"></a>      <span class="dt">&quot;RemoteSha&quot;</span><span class="fu">:</span> <span class="st">&quot;1763e0dcb72fb58d97bab97bb834fc71f1e012bc&quot;</span><span class="fu">,</span></span>
<span id="cb1-29"><a href="#cb1-29" tabindex="-1"></a>      <span class="dt">&quot;Requirements&quot;</span><span class="fu">:</span> <span class="ot">[</span></span>
<span id="cb1-30"><a href="#cb1-30" tabindex="-1"></a>        <span class="st">&quot;tools&quot;</span></span>
<span id="cb1-31"><a href="#cb1-31" tabindex="-1"></a>      <span class="ot">]</span><span class="fu">,</span></span>
<span id="cb1-32"><a href="#cb1-32" tabindex="-1"></a>      <span class="dt">&quot;Hash&quot;</span><span class="fu">:</span> <span class="st">&quot;c2772b6269924dad6784aaa1d99dbb86&quot;</span></span>
<span id="cb1-33"><a href="#cb1-33" tabindex="-1"></a>    <span class="fu">}</span></span>
<span id="cb1-34"><a href="#cb1-34" tabindex="-1"></a>  <span class="fu">}</span></span>
<span id="cb1-35"><a href="#cb1-35" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
<p>As you can see the json file has two main components: <code>R</code>
and <code>Packages</code>. The <code>R</code> component contains the
version of R used, and a list of repositories where packages were
installed from. The <code>Packages</code> contains one record for each
package used by the project, including all the details needed to
re-install that exact version. The fields written into each package
record are derived from the installed package’s <code>DESCRIPTION</code>
file, and include the data required to recreate installation, regardless
of whether the package was installed from <a href="https://cran.r-project.org/">CRAN</a>, <a href="https://www.bioconductor.org/">Bioconductor</a>, <a href="https://github.com/">GitHub</a>, <a href="https://about.gitlab.com/">Gitlab</a>, <a href="https://bitbucket.org/">Bitbucket</a>, or elsewhere. You can learn
more about the sources renv supports in
<code>vignette(&quot;package-sources&quot;)</code>.</p>
</div>
<div id="caveats" class="section level2">
<h2>Caveats</h2>
<p>It is important to emphasize that renv is not a panacea for
reproducibility. Rather, it is a tool that can help make projects
reproducible by helping with one part of the overall problem: R
packages. There are a number of other pieces that renv doesn’t currently
provide much help with:</p>
<ul>
<li><strong>R version</strong>: renv tracks, but doesn’t help with, the
version of R used with the project. renv can’t easily help with this
because it’s run inside of R, but you might find tools like <a href="https://github.com/r-lib/rig">rig</a> helpful, as they make it
easier to switch between multiple version of R on one computer.</li>
<li><strong>Pandoc</strong>: The rmarkdown package relies heavily on <a href="https://pandoc.org/">pandoc</a>, but pandoc is not bundled with
the rmarkdown package. That means restoring rmarkdown from the lockfile
is insufficient to guarantee exactly the same rendering of RMarkdown
documents. If this causes problems for you, you might find the tools
provided by the <a href="https://cderv.github.io/pandoc/">pandoc
package</a> to be useful.</li>
<li><strong>Operating system, versions of system libraries, compiler
versions</strong>: Keeping a ‘stable’ machine image is a separate
challenge, but <a href="https://www.docker.com/">Docker</a> is one
popular solution. See <code>vignette(&quot;docker&quot;, package = &quot;renv&quot;)</code>
for recommendations on how Docker can be used together with renv.</li>
</ul>
<p>You also need to be aware that package installation may fail if a
package was originally installed through a binary, but that binary is no
longer available. renv will attempt to install the package from source,
but this can (and often will) fail due to missing system
prerequisites.</p>
<p>Ultimately, making a project reproducible will always require
thought, not just mechanical usage of a tool: what does it mean for a
particular project to be reproducible, and how can you use tools to meet
that particular goal of reproducibility?</p>
</div>
<div id="uninstalling-renv" class="section level2">
<h2>Uninstalling renv</h2>
<p>If you find renv isn’t the right fit for your project, deactivating
and uninstalling it is easy.</p>
<ul>
<li><p>To deactivate renv in a project, use
<code>renv::deactivate()</code>. This removes the renv auto-loader from
the project <code>.Rprofile</code>, but doesn’t touch any other renv
files used in the project. If you’d like to later re-activate renv, you
can do so with <code>renv::activate()</code>.</p></li>
<li><p>To completely remove renv from a project, call
<code>renv::deactivate(clean = TRUE)</code>. If you later want to use
renv for this project, you’ll need to start from scratch with
<code>renv::init().</code></p></li>
</ul>
<p>If you want to stop using renv for all your projects, you’ll also
want to remove <code>renv&#39;</code>s global infrastructure with the
following R code<a href="#fn6" class="footnote-ref" id="fnref6"><sup>6</sup></a>:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb2-1"><a href="#cb2-1" tabindex="-1"></a>root <span class="ot">&lt;-</span> renv<span class="sc">::</span>paths<span class="sc">$</span><span class="fu">root</span>()</span>
<span id="cb2-2"><a href="#cb2-2" tabindex="-1"></a><span class="fu">unlink</span>(root, <span class="at">recursive =</span> <span class="cn">TRUE</span>)</span></code></pre></div>
<p>You can then uninstall the renv package with
<code>utils::remove.packages(&quot;renv&quot;)</code>.</p>
</div>
<div class="footnotes footnotes-end-of-document">
<hr />
<ol>
<li id="fn1"><p>More precisely, there can be up to three system
libraries: an (optional) <strong>user</strong> library, an (optional)
<strong>site</strong> library, and a <strong>default</strong> library
(where base R packages are installed).<a href="#fnref1" class="footnote-back">↩︎</a></p></li>
<li id="fn2"><p>If you’d like to skip dependency discovery, you can call
<code>renv::init(bare = TRUE)</code> to initialize a project with an
empty project library.<a href="#fnref2" class="footnote-back">↩︎</a></p></li>
<li id="fn3"><p>If you’re using another version control system, you’ll
need to manually ignore <code>renv/library</code> and any other
directories in <code>renv/</code>.<a href="#fnref3" class="footnote-back">↩︎</a></p></li>
<li id="fn4"><p>Behind the scene, renv shims
<code>install.packages()</code>, <code>update.packages(),</code> and
<code>remove.packages()</code> to call the renv equivalents. Learn more
in <code>?renv::load.</code><a href="#fnref4" class="footnote-back">↩︎</a></p></li>
<li id="fn5"><p>You can also use <code>update.packages()</code>, but
<code>renv::update()</code> works with the same sources that
<code>renv::install()</code> supports.<a href="#fnref5" class="footnote-back">↩︎</a></p></li>
<li id="fn6"><p>If you’ve customized any of renv’s infrastructure paths
as described in <code>?renv::paths</code>, then you’ll need to find and
remove those customized folders as well.<a href="#fnref6" class="footnote-back">↩︎</a></p></li>
</ol>
</div>



<!-- code folding -->


<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>

</body>
</html>
